﻿<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="../helpproject.xsl" ?>
<topic template="Default" lasteditedby="Geert" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../helpproject.xsd">
  <title translate="true">Catel.Fody</title>
  <keywords>
    <keyword translate="true">AOP</keyword>
    <keyword translate="true">Catel.Fody</keyword>
    <keyword translate="true">Fody</keyword>
    <keyword translate="true">IL</keyword>
    <keyword translate="true">Weaving</keyword>
  </keywords>
  <body>
    <header>
      <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Catel.Fody</text></para>
    </header>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Fody is an extensible tool for weaving .NET assemblies. For more information about Fody, see </text><link displaytype="text" defaultstyle="true" type="weblink" href="http://code.google.com/p/fody/" target="_blank" styleclass="Normal" translate="true">its official website</link><text styleclass="Normal" translate="true">. The </text><link displaytype="text" defaultstyle="true" type="weblink" href="http://code.google.com/p/propertychanged/" target="_blank" styleclass="Normal" translate="true">PropertyChanged.Fody</link><text styleclass="Normal" translate="true"> plugin for Fody already supports Catel out of the box, but only for property change notifications. However, with the </text><text styleclass="Normal" style="font-style:italic;" translate="true">Catel.Fody</text><text styleclass="Normal" translate="true"> plugin, it is possible to automatically weave a simple property into a Catel property. </text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">The following property definition:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">public</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">string</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">Name</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">{</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">get;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">set;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">}</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">will be weaved into:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">public</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">string</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">Name</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">{</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">get</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">{</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">return</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">GetValue&lt;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">string</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&gt;(NameProperty);</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">}</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">set</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">{</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">SetValue(NameProperty,</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">value);</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">}</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">}</text><br/><br/><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">public</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">static</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">readonly</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">PropertyData</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">NameProperty</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">RegisterProperty(&quot;Name&quot;,</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">typeof</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">(</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">string</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">));</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">In the background, Catel.Fody will handle the following workflow:</text></para>
    <list id="3" type="ol" listtype="decimal" formatstring="&#37;&#48;&#58;&#115;&#46;" format-charset="DEFAULT_CHARSET" levelreset="true" legalstyle="false" startfrom="1" styleclass="Normal (list)" style="font-family:Arial; font-size:10pt; color:#000000;">
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Find all types in the assembly deriving from </text><text styleclass="Normal (list)" style="font-style:italic;" translate="true">ModelBase</text><text styleclass="Normal (list)" translate="true"> (thus also ViewModelBase)</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Check if the type has an automatic property backing field (only those properties are weaved)</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Add the </text><text styleclass="Normal (list)" style="font-style:italic;" translate="true">PropertyData</text><text styleclass="Normal (list)" translate="true"> field for the property</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Instantiate the </text><text styleclass="Normal (list)" style="font-style:italic;" translate="true">PropertyData</text><text styleclass="Normal (list)" translate="true"> field in the static constructor of the type</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Replace the content of the getter and setter with the appropriate calls to </text><text styleclass="Normal (list)" style="font-style:italic;" translate="true">GetValue</text><text styleclass="Normal (list)" translate="true"> and </text><text styleclass="Normal (list)" style="font-style:italic;" translate="true">SetValue</text></li>
    </list>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">How to weave assemblies with Catel properties</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">To weave assemblies with Catel properties, you need to perform the following steps:</text></para>
    <list id="4" type="ol" listtype="decimal" formatstring="&#37;&#48;&#58;&#115;&#46;" format-charset="DEFAULT_CHARSET" levelreset="true" legalstyle="false" startfrom="1" styleclass="Normal (list)" style="font-family:Arial; font-size:10pt; color:#000000;">
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Install the </text><link displaytype="text" defaultstyle="true" type="weblink" href="http://visualstudiogallery.msdn.microsoft.com/074a2a26-d034-46f1-8fe1-0da97265eb7a" target="_blank" styleclass="Normal (list)" translate="true">Fody Visual Studio extension</link></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Install the </text><text styleclass="Normal (list)" style="font-style:italic;" translate="true">Catel.Fody</text><text styleclass="Normal (list)" translate="true"> NuGet package</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Enable Fody for the target project using </text><text styleclass="Normal (list)" style="font-style:italic;" translate="true">Project</text><text styleclass="Normal (list)" translate="true"> =&gt; </text><text styleclass="Normal (list)" style="font-style:italic;" translate="true">Fody</text><text styleclass="Normal (list)" translate="true"> =&gt; </text><text styleclass="Normal (list)" style="font-style:italic;" translate="true">Enable</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" style="font-style:normal;" translate="true">Update </text><text styleclass="Normal (list)" style="font-style:italic;" translate="true">Weavers.xml</text><text styleclass="Normal (list)" style="font-style:normal;" translate="true"> and add </text><text styleclass="Normal (list)" style="font-style:italic;" translate="true">&lt;Catel /&gt;</text><text styleclass="Normal (list)" style="font-style:normal;" translate="true"> to it</text></li>
    </list>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">How to exclude properties</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Sometimes properties should not be weaved into Catel properties. Catel.Fody does its best to recognize properties that shouldn&apos;t be weaved automatically, but this might not be enough. Therefore, it is possible to use the </text><text styleclass="Normal" style="font-style:italic;" translate="true">DoNotWeave</text><text styleclass="Normal" translate="true"> attribute on a property.</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">[DoNotWeave]</text><br/><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">public</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">string</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">Name</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">{</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">get;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">set;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">}</text></para>
    <para styleclass="Normal"><text styleclass="Normal" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">When a property is decorated with the </text><text styleclass="Normal" style="font-weight:normal; font-style:italic; color:#000000;" translate="true">DoNotWeave</text><text styleclass="Normal" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> attribute, it will not be touched by Catel.Fody.</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Automatically excluded properties</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">By default, Catel.Fody ignores the following properties and types by default because they shouldn&apos;t be weaved:</text></para>
    <list id="5" type="ul" listtype="bullet" formatstring="&#183;" format-charset="SYMBOL_CHARSET" levelreset="true" legalstyle="false" startfrom="1" styleclass="Normal (list)" style="font-family:Symbol; font-size:10pt; color:#000000;">
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">All properties of type </text><text styleclass="Normal (list)" style="font-style:italic;" translate="true">ICommand</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Properties without an automatically generated backing field</text></li>
    </list>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">How to get automatic change notifications</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">So, the Fody plugin for Catel automatically searches for the </text><text styleclass="Normal" style="font-style:italic;" translate="true">On[PropertyName]Changed</text><text styleclass="Normal" translate="true"> methods. If a method is found, it will automatically be called when the property has changed. For example, the </text><text styleclass="Normal" style="font-style:italic;" translate="true">OnNameChanged</text><text styleclass="Normal" translate="true"> is automatically called when the </text><text styleclass="Normal" style="font-style:italic;" translate="true">Name</text><text styleclass="Normal" translate="true"> property is changed in the example below:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">public</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">string</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">Name</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">{</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">get;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">set;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">}</text><br/><br/><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">private</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">void</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">OnNameChanged()</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">{</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#000000;" translate="true">// this method is automatically called when the Name property changes</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">}</text></para>
  </body>
</topic>
